docs(agents): state the app-vs-platform boundary once, so it stops being re-derived - #15427

Part of #15420.

The boundary was decided ad hoc three times in one day, by three seats, each from scratch, and the three derivations differed. This states it once. Re-based and re-paid against the new 1058 ceiling: AGENTS.md is net ±0 lines, and the ceiling is untouched.

⛔ AGENTS.md and .claude/skills/** are governed surfaces: no auto-merge armed, nothing self-approved, landing is the maintainer's by hand.

⚠️ Re-baselined — the floor moved after this PR was approved

The rules-only rewrite compressed AGENTS.md 1161 → 1058 and, by its own discipline, locked the ceiling to 1058. That was the right thing to do, but it took back the single line of headroom this PR's pointer had been paid from. Combined:

main's AGENTS.md            1058 lines
main's ratchet ceiling      1058          <- headroom 0
this PR merged into main    1059 lines    <- over by 1

⚠️ Three signals all said "fine", because all three are textual. The PR's own CI was green on the old baseline; mergeable_state was clean; git merge-tree reported no conflict. Git merged the two edits cleanly — they are nowhere near each other. The failure only materialises when a gate counts lines in the merged result, which is the merge queue, i.e. after being queued and kicked out.

The check that actually catches this class, and the one now used here:

TREE=$(git merge-tree --write-tree origin/main HEAD | head -1)
git cat-file -p $TREE:AGENTS.md | wc -l

The arithmetic, spelled out

Whole diff against main: 3 files, 76 insertions, 1 deletion. That single deletion is the standalone row being folded, not a rule being dropped.

How the line was re-paid: a net-zero fold, not a raise and not a re-wrap

The earlier revision added a standalone Scope Triage row. With headroom now 0 that row had to pay for itself, and the two funding routes an author may take alone are both closed (below). So the row is folded into the examples/** row that was already in the table:

• the Example Author constraint is preserved verbatim — "Minimal, runnable, uses defineStack"
• the boundary question is worded "on any tree", so folding it onto that row does not scope a repo-wide rule to that directory
• net effect on the file: +1 / −1 = 0 lines

⛔ No line was reclaimed by re-wrapping, ⛔ no existing rule was deleted or shortened, ⛔ the ceiling was not touched.

The real run, verdict lines quoted verbatim

pnpm check:pm-skill-ratchet at the final head 088d652fb — exit 0:

✓ check-skill-line-ratchet self-test: 155 cases pass.
✓ check-skill-line-ratchet: AGENTS.md is 1058 lines (ceiling 1058; headroom 0).
✓ check-skill-line-ratchet: AGENTS.md: widest table row is 768 bytes (pin 768; headroom 0).
✓ check-skill-line-ratchet: .claude/skills/pm-dispatch/references/app-platform-boundary.md is 66 lines (ceiling 66; headroom 0).
✓ check-skill-line-ratchet: .claude/skills/pm-dispatch/references/app-platform-boundary.md: widest table row is 219 bytes (pin 219; headroom 0).

And measured inside the merged-with-main tree, which is the reading the merge queue will take:

AGENTS.md lines in merged tree : 1058   (ceiling 1058)
longest line in merged tree    : 768    (pin 768)

The second pin moved too — measured by hand, not left to the gate

MAX_TABLE_ROW_BYTES for AGENTS.md dropped 1081 → 768, and main sits exactly on 768. Measured with LC_ALL=C awk '{print length}' AGENTS.md | sort -rn | head -1:

origin/main   : 768
this branch   : 768     <- unchanged, my row is not the widest
the folded row: 323 bytes

Why the rule is not 8-12 lines of AGENTS.md prose

Headroom is 0, and both funding routes an author may take alone are closed:

1. Re-wrap funding is banned — the 2026-08-17 筹行 ruling, cited throughout the ratchet's own source, because "the ratchet governs content volume and lines are only its machine-readable proxy". Precedent is explicit: on .claude/agents/os-dev.md re-wrap funding was available and was refused in favour of a ruled raise.
2. A declared cross-file move cannot fund new content — the arithmetic cancels. Condition (a) is that the destination's raise is at most the net decrease of the sources. If AGENTS.md gives up N lines its ceiling falls by N, so the test becomes 1058 − N + K ≤ 1058 − N, i.e. K ≤ 0 for any N. By design: the header says a move is "never as a way to grow the corpus".

So the split follows the ratchet's own division of labour — the remedy sentence it prints when it goes red: principles in the instruction file, on-demand detail in references/.

• AGENTS.md carries the deciding question and the pointer, inside a row it already had.
• The rule itself lives in .claude/skills/pm-dispatch/references/app-platform-boundary.md: the deciding question with its table, the publication test, and both anti-patterns with the measurement behind each.
• The new file arrives metered, entered in both ratchet maps at its landed count — otherwise it would be an un-ceilinged file inside a ratcheted directory, the exact hole the ratchet exists to close.

Traceability — carried self-contained, not by issue number

check:pm-skill-id-lint went red on the first draft with 6 issue-ID citations. Maintainer ruling 2026-08-12, verbatim and untranslated:

「立一张结构卡,我觉的处理 issue 时犯的错应该总结成经验,保留 issue id没有意义,如果ai去查原始issue,得不偿失。」

That gate scans everything under .claude/skills/pm-dispatch/, so it governs the new reference file too. Both files therefore carry each lesson self-contained — failure mode, discipline, boundary — and cite source paths rather than issue numbers. Provenance for review:

• the publication test — a resolution wanted by four call sites in one package stayed package-private; maintainer decision on feat(runtime): every top-level collection read gains a packages[] path (#15005) #15261, which published nothing
• anti-pattern 1 — 17.3.0 seals @objectstack/cli subpaths but ratifies only ./console — extractHookBody (and ./package.json) have no public entry, and an app's hook-body fidelity harness breaks with no replacement #15325 (half the need was already os build --strict-body; the other half named an os lint rule that exists nowhere in the tree) and finding — a gating lint rule shipped claiming "0 findings over the corpus" and names an object that fires it; the corpus copy is not the real app #15357 (a rule shipped claiming "0 findings over the corpus" against a corpus that was not the app it named)
• anti-pattern 2 — record — the option-B reader by-shape sweep: method, derived 37-key collection set, triaged false positives, and the two packages it found #15210's by-shape sweep, and the ordered pair under reader program 5/4 — @objectstack/verify: an option-B artifact makes os verify report a green run that measured nothing #15229

Re-verified against the tree rather than taken from the card: os build --strict-body is real (packages/cli/src/commands/compile.ts, of which build is an alias); verify.ts carries the anti-pattern's own sentence — "a verifier that under-verifies reports success it never established". ⚠️ os verify's zero-case defect was closed before this branch's base, so it is written as a landed lesson, not a live defect.

Verdict: CLAUDE.md — NO, do not mirror

For: the rule is repo-wide, applies to every seat, and the file has ratchet headroom — the cheapest place in the repo to put anything.

Against, and this wins:

1. Its bar is not "important", it is "missing one wastes or corrupts other agents' work". All four inlined rules are cross-agent collisions the victim cannot prevent: two agents burn the same card; your HEAD switch clobbers another's uncommitted tree; your pop takes another's stash entry; your release-notes row conflicts with eighteen merges. This rule is different in kind — getting it wrong costs your own card's hours and yields a reviewable PR. feat(runtime): every top-level collection read gains a packages[] path (#15005) #15261 is the proof: caught on contract review, rejected, rewritten, no other agent harmed.
2. Each of the four names its enforcing hook, or explicitly says "No hook enforces this one". They are inlined because the damage is irreversible at the instant of the write. This rule has no such instant.
3. It is a design judgement, not a mechanical prohibition. Compressed to one sentence plus a pointer it becomes the "as a rule we prefer…" mush the card bans.
4. Headroom is not a licence. The ratchet's own entry for that file calls it "structurally growth-prone in the way the ratchet is built for: it exists to inline the rules that must never be missed, so every new must-never-miss rule is an argument for appending to it."

Verdict: the 11 published skills — read, not assumed

objectstack-platform already owns this question. It carries a section titled "The App / Platform Boundary" whose first bullet is "Business features belong in the app; capability belongs in the platform", and it already carries anti-pattern 1 nearly verbatim: "no hand-written predicate re-implementing a platform rule". The card's guess was right — the doctrine has a home.

objectstack-pm-dispatch — NO. Its "Upstream reporting" section defers to that section by name: "The doctrine lives in objectstack-platform under The App / Platform Boundary". Single-owner is already the arrangement; a second copy is a drift site.

objectstack-upgrade — NO. Its ⛔ The boundary section is a different boundary — conversion chain versus hand edits — and already carries its own scoped instance of anti-pattern 1. The general rule there would duplicate platform's, in a skill loaded only during a major upgrade.

The other eight (ai, api, automation, data, formula, i18n, query, ui) — NO. Each is a metadata-authoring domain skill; the boundary is not a per-domain authoring question, and eight copies is eight drift sites.

The publication half must NOT ship to customers. "Would a second app copy the implementation?" decides what a package in this monorepo exports. A customer app author cannot act on it — contributor guidance, pure noise there.

The one genuine app-facing gap — objectstack-platform states which side owns what but not how to tell. Filed as #15428 rather than ridden in here, because skills/** is a separate customer-visible governed surface with its own token budget.

Verification

Gate family re-derived at the final head, not recalled: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack → 39 runnable families. All 39 run at 088d652fb under the shared verification lock, every exit code captured before any pipe (cmd > log 2>&1; EXIT=$?).

• 39 green, including check:pm-skill-ratchet, check:pm-skill-id-lint, check:ratchet-remedy-authority, check:skill-frame-sync, check:pm-dispatch-gates, check:pm-governed-prose, check:pm-governed-merges, check:nul-bytes, check:required-contexts, check:cross-package-test-inputs, check:self-test-wired, and both check-closing-keyword-parity spellings with their self-tests. Every script that reads the ratchet's maps is in this set, so the map edit is mirror-checked.
• One gate first reported PREREQUISITE NOT MET (exit 3) and was re-run rather than recorded as a failure: check:doc-formula-expressions needed @objectstack/formula and @objectstack/lint built; green after building both.
• Byte discipline: the control-character grep matches nothing in either edited markdown file; no non-table line in either exceeds 120 bytes.

⛔ No code, no test and no os verify change. ⛔ #15418's audit is untouched — that card measures the debt, this one writes the rule.

Changeset

None, deliberately — skip-changeset is applied and correct; an empty changeset would be wrong. The diff is one root governance document, one internal agent reference, and one internal gate script: it publishes nothing from any released package.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m